Release 10.1A: OpenEdge Development:
Progress 4GL Reference

COPY-DATASET( ) method

Copies a source ProDataSet object to a target ProDataSet object. Progress empties the target ProDataSet object temp-tables of all records before copying the source ProDataSet object, by default.

Return type: LOGICAL

Applies to: ProDataSet object handle

Syntax

targ-dataset-handle:COPY-DATASET( src-dataset-handle [, append-mode [, replace-mode [, loose-copy-mode [, pairs-list [, current-only ] ] ] ] ] )

targ-dataset-handle

The handle to the target ProDataSet object to receive the copy.

src-dataset-handle

The handle to the source ProDataSet object from which to copy.

append-mode

An optional logical expression where TRUE indicates that Progress copy the ProDataSet object temp-tables in an append mode.

When TRUE, Progress appends the source ProDataSet temp-tables to the target ProDataSet temp-tables. If there is a unique index on a target temp-table and Progress finds a row with a duplicate key, it does not replace the row. If there is not a unique index on the target temp-table, Progress appends the data row from the source temp-table to the target temp-table, which might result in duplicate rows. If this operation results in duplicate rows, Progress does not generate a run-time error.

Note: In this mode, Progress treats duplicate temp-table rows during the copy operation in the same way it treats duplicate temp-table rows during a fill operation in MERGE mode.

When you are certain the ProDataSet temp-tables do not contain duplicate rows, copying the ProDataSet object in append mode is more efficient than copying it in replace mode.

When FALSE, Progress does not append records in the target ProDataSet temp-tables. The default value is FALSE.

Progress ignores this expression when replace-mode is TRUE.

replace-mode

An optional logical expression where TRUE indicates that Progress copy the ProDataSet object temp-tables in a replace mode.

When TRUE, Progress replaces records in the target ProDataSet object temp-tables with corresponding records from the source ProDataSet temp-tables. In this case, the source and target temp-tables must be named differently, the target temp-table must have a unique primary index that Progress can use to find the corresponding records. When a corresponding record is found in the target temp-table, Progress replaces the target record with the source record. When a corresponding record is not found in the target temp-table, Progress creates a new target record using the source record. If the before-image table associated with the target temp-table contains a row for the target record, the row is left in place.

Copying ProDataSet object temp-tables in replace mode is less efficient than copying them in append mode. When you are certain the ProDataSet object temp-tables do not contain duplicate rows, copy the ProDataSet object in append mode.

When FALSE, Progress does not replace records in the target ProDataSet object temp-tables. The default value is FALSE.

loose-copy-mode

An optional logical expression where TRUE indicates that Progress copy the ProDataSet object temp-tables in a loose-copy mode. That is, it relaxes the requirement that the meta-schema for the source and target temp-tables be the same.

When TRUE, Progress copies each temp-table in the source ProDataSet object to the target ProDataSet object based on a field mapping between the source and target temp-table buffers. If there is an attached data source with a field mapping, Progress uses that field mapping to copy fields from each source temp-table buffer to its target temp-table buffer. If there are fields in either buffer that do not exist in the other, they are ignored. If there is no field mapping with the attached data source, or there is no attached data source, Progress copies only those fields that appear in both the source and target temp-table meta-schemas with the same name.

When FALSE, the meta-schema for the source and target temp-tables must be the same or Progress generates a run-time error. The default value is FALSE.

pairs-list

An optional character expression that evaluates to a comma-separated list of the target and source temp-table pairs to be copied. Following is the pairs-list syntax:

target-table1, source-table1 [, target-table2, source-table2 ] ...)

If specified, Progress copies only the listed temp-tables by matching the target and source temp-table names.

If not specified, Progress copies all the temp-tables in the order they were defined or added in the ProDataSets. If either the source or target ProDataSet has one or more extra temp-tables at the end, the extra temp-tables are ignored.

current-only

An optional logical expression where TRUE indicates that Progress copy only the current record from each temp-table at each level in the source ProDataSet object to the target ProDataSet object. The default value is FALSE.

Note: You might need to synchronize the buffers to ensure they are the related buffers. Once you have read a record into a top-level buffer, you can synchronize the related buffers by calling the SYNCHRONIZE( ) method.

To copy the current record from a single temp-table, you can use the BUFFER-COPY statement or BUFFER-COPY( ) method.

Notes

If the source ProDataSet object has any before-image tables that contain changed row data for any associated temp-tables, Progress generates a run-time error.
When Progress copies the source ProDataSet object, it copies each temp-table in the order in which the temp-table was defined, and in its entirety. That is, it does not copy the temp-tables in an interleaved and nested manner based on their data relations. If either the source or target ProDataSet has one or more extra temp-tables at the end, the extra temp-tables are ignored.
When Progress copies a ProDataSet object in any mode, except loose-copy mode, and the target ProDataSet object has a meta-schema (that is, temp-table and relation definitions), the source ProDataSet object meta-schema must be the same. If the source and target ProDataSet object meta-schema is not the same, Progress generates a run-time error. If the target ProDataSet object is a newly created dynamic object with only a handle and no meta-schema, Progress copies the source ProDataSet object including its meta-schema. In this case, Progress names the temp-tables in the target object by taking the names of the temp-tables in the source object and prepending a "cpy_" prefix to them.

See also

ATTACH-DATA-SOURCE( ) method, FILL-MODE attribute, COPY-TEMP-TABLE( ) method